---
title: "Tool Optimization (MCP & Function Calling)"
subtitle: "Optimize prompts that use external tools and function calls"
description: "Learn how to optimize prompts that leverage MCP (Model Context Protocol) tools and function calling capabilities using the MetaPrompt Optimizer."
---

Tool optimization is a specialized feature that allows you to optimize prompts that use external tools and the Model Context Protocol (MCP). This capability is currently **exclusively supported by the MetaPrompt Optimizer** and is **currently in Beta**.

## What is Tool Optimization?

Tool optimization extends traditional prompt optimization to handle prompts that include:

- **MCP tools** - Model Context Protocol tools for external integrations (Beta)
- **Tool schemas** - Structured tool definitions and parameters
- **Multi-step workflows** - Complex agent workflows involving multiple tools

<Note>
  **Important Distinction:** Many optimizers (including GEPA, MetaPrompt, etc.) can optimize **agents that use tools** -
  this means optimizing prompts for agents that have access to function calling or external tools. However, **true tool
  optimization** (optimizing the tools themselves, their schemas, or MCP integrations) is currently only available
  through MetaPrompt Optimizer and is in Beta.
</Note>

<Note>

**Why Tool Optimization Matters:**

Traditional prompt optimization focuses on text-based prompts, but modern AI applications often
require:

- Integration with external APIs and services
- Structured data processing through function calls
- Complex multi-step reasoning with tool usage
- Dynamic tool selection based on context Tool optimization ensures these sophisticated prompts
  can be improved just like simple text prompts.

</Note>

## Supported Tool Types

### 1. Agent Function Calling (Not True Tool Optimization)

Many optimizers can optimize **agents that use function calling**, but this is different from true tool optimization. Here's an example from the GEPA optimizer:

```python
from opik_optimizer import GepaOptimizer, ChatPrompt

# GEPA example: optimizing an agent with function calling
prompt = ChatPrompt(
    system="You are a helpful assistant. Use the search_wikipedia tool when needed.",
    user="{question}",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "search_wikipedia",
                "description": "This function searches Wikipedia abstracts.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {
                            "type": "string",
                            "description": "The term or phrase to search for."
                        }
                    },
                    "required": ["query"]
                }
            }
        }
    ],
    function_map={
        "search_wikipedia": lambda query: search_wikipedia(query, use_api=True)
    }
)

# GEPA optimizes the agent's prompt, not the tools themselves
optimizer = GepaOptimizer(model="gpt-4o-mini")
result = optimizer.optimize_prompt(prompt=prompt, dataset=dataset, metric=metric)
```

<Note>
  This is **agent optimization** (optimizing prompts for agents that use tools), not **tool optimization** (optimizing
  the tools themselves).
</Note>

### 2. MCP (Model Context Protocol) Tools - Beta

**True tool optimization** is currently only available for MCP tools and is in Beta. MCP tools provide standardized interfaces for external integrations:

```python
# MCP tool optimization example (Beta)
# See scripts/litellm_metaprompt_context7_mcp_example.py for working examples

from opik_optimizer import MetaPromptOptimizer

# MCP tools are configured through mcp.json manifests
# The MetaPrompt Optimizer can optimize MCP tool descriptions and usage
optimizer = MetaPromptOptimizer(model="gpt-4")

# MCP tool optimization is currently in Beta
# Check the scripts/ directory for working examples
```

<Note>
MCP Tool Optimization Status:

    - Currently in **Beta**
    - Only supported by **MetaPrompt Optimizer**
    - See [PR#3341](https://github.com/comet-ml/opik/pull/3341) for implementation detail
    - Working examples available in `scripts/litellm_metaprompt_context7_mcp_example.py`

</Note>

## How Tool Optimization Works

The MetaPrompt Optimizer handles tool-enabled prompts through a specialized optimization process:

### 1. Tool-Aware Analysis

The optimizer analyzes:

- **Tool schemas** - Understanding available functions and their parameters
- **Tool usage patterns** - How tools are typically invoked in the prompt
- **Tool dependencies** - Relationships between different tools
- **Context requirements** - What information tools need to function effectively

### 2. Prompt-Tool Integration Optimization

The optimizer can improve:

- **Tool selection logic** - Better instructions for when to use which tools
- **Parameter formatting** - Clearer guidance on how to structure tool inputs
- **Error handling** - Instructions for handling tool failures or edge cases
- **Tool chaining** - Optimizing multi-step tool workflows

### 3. Context Enhancement

Tool optimization also improves:

- **Input validation** - Better prompts for validating tool inputs
- **Output processing** - Instructions for handling tool outputs
- **Fallback strategies** - Alternative approaches when tools are unavailable

## Example: Optimizing a Research Assistant

Let's see how tool optimization works with a research assistant that uses multiple tools:

```python
from opik_optimizer import MetaPromptOptimizer, ChatPrompt
from opik.evaluation.metrics import LevenshteinRatio

# Define a research assistant prompt with tools
research_prompt = ChatPrompt(
    messages=[
        {
            "role": "system",
            "content": """You are a research assistant. When given a research question:
1. Search for relevant information using the search tool
2. Analyze the results using the analysis tool
3. Provide a comprehensive answer based on your findings

Always cite your sources and be thorough in your research."""
        },
        {
            "role": "user",
            "content": "{research_question}"
        }
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "search_academic_database",
                "description": "Search academic papers and research",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"},
                        "year_range": {"type": "string"},
                        "max_results": {"type": "integer"}
                    }
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "analyze_text",
                "description": "Analyze and summarize text content",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "text": {"type": "string"},
                        "analysis_type": {"type": "string"}
                    }
                }
            }
        }
    ]
)

# Initialize the optimizer
optimizer = MetaPromptOptimizer(
    model="openai/gpt-4",
    reasoning_model="openai/gpt-4-turbo"
)

# Define evaluation metric
def research_quality_metric(dataset_item, llm_output):
    return LevenshteinRatio().score(
        reference=dataset_item['expected_answer'],
        output=llm_output
    )

# Run optimization
result = optimizer.optimize_prompt(
    prompt=research_prompt,
    dataset=research_dataset,
    metric=research_quality_metric,
    n_samples=100,
    max_rounds=5
)

print("Optimized prompt with tools:")
print(result.prompt)
```

## Best Practices for Tool Optimization

### 1. Tool Schema Design

- **Clear descriptions** - Provide detailed descriptions for each tool
- **Comprehensive parameters** - Include all necessary parameters with types
- **Example usage** - Add examples in tool descriptions when helpful
- **Error handling** - Define expected error conditions and responses

### 2. Prompt Structure

- **Tool introduction** - Clearly explain available tools to the model
- **Usage guidelines** - Provide specific instructions on when and how to use tools
- **Output formatting** - Specify how tool outputs should be processed
- **Fallback instructions** - Define what to do when tools fail

### 3. Evaluation Considerations

- **Tool usage metrics** - Measure not just final output quality but tool usage effectiveness
- **Multi-step evaluation** - Evaluate each step in tool-based workflows
- **Error rate tracking** - Monitor tool failure rates and recovery strategies
- **Context preservation** - Ensure important context is maintained across tool calls

## Limitations and Considerations

### Current Limitations

- **MetaPrompt Only** - Tool optimization is currently only available with the MetaPrompt Optimizer
- **Tool Complexity** - Very complex tool workflows may require manual optimization
- **Tool Availability** - Optimization assumes tools are available during evaluation
- **Schema Changes** - Tool schema modifications may require re-optimization

### Performance Considerations

- **Evaluation Cost** - Tool-enabled prompts require more LLM calls for evaluation
- **Tool Latency** - External tool calls can slow down optimization
- **Resource Usage** - Complex tool workflows may require significant computational resources

## Future Roadmap

Tool optimization is an active area of development. Planned improvements include:

- **Multi-optimizer support** - Extending tool optimization to other optimizers
- **Tool-specific metrics** - Specialized evaluation metrics for tool usage
- **Automated tool discovery** - Automatic detection and optimization of tool patterns
- **Tool performance optimization** - Optimizing not just prompts but tool usage efficiency

## Getting Started

To start optimizing tool-enabled prompts:

1. **Choose MetaPrompt Optimizer** - Currently the only optimizer supporting tool optimization
2. **Define your tools** - Create clear tool schemas with comprehensive descriptions
3. **Structure your prompt** - Include clear instructions for tool usage
4. **Prepare evaluation data** - Ensure your dataset includes tool usage scenarios
5. **Run optimization** - Use the standard optimization process with tool-enabled prompts

<Info>
**Need Help?**

For questions about tool optimization or to request support for additional optimizers, please reach out
on [GitHub](https://github.com/comet-ml/opik/issues) or check the [MetaPrompt Optimizer
documentation](/agent_optimization/algorithms/metaprompt_optimizer) for detailed configuration options.

</Info>

## References

- [MetaPrompt Optimizer Documentation](/agent_optimization/algorithms/metaprompt_optimizer)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
